Release notes

2024r2

Parent series not allowed for content collection calls of content API

In a previous version, the content API was adapted for content collections on parent series. They can only be edited by adding or removing items using the /contentCollectionItems calls, not the /series calls.

Since nothing else can be changed on the parent series content collection, it was intended to use the /series calls to update the parent series and not the /contentCollection calls.

However, when the ID (external reference) of a parent series was provided in the URL of the /contentCollection calls, changes were still accepted.

From this version, when the external reference of a parent series is provided in the URL of the GET, POST, PUT or DELETE /contentCollection calls, the following error is returned:

{
    "statusCode": "404",
    "message": "The specified resource does not exist.",
    "timestamp": "2024-03-01T14:33:40Z",
    "concept": "Content Collection",
    "id": "32614015BE",
    "errors": [
        {
            "errorCode": "404",
            "description": "The specified resource does not exist.",
            "data": []
        }
    ]
}

Only the external reference of series (standard seasons or content collections) are now accepted in these calls. Parent series should be updated using the /series calls and /contentCollectionItems calls to add or remove items.

API developers

For API developers: a description was added to the requestBody of the following paths:

  • 855:  '/contentCollections':
  • 856:    post:
    The addition is at line 870
  • 898:  '/contentCollections/{contentId}':
  • 899:    put:
    The addition is at line 911
  • 934:    get:
    The addition is at line 936
  • 984:    delete:
    The addition is at line 986
      requestBody:
        required: true
        description: >
          **Note**: Attribute "ContentId" cannot be the external reference of a parent series. 
          Manipulations on parent series should always be done using the dedicated series call

For easier viewing, the YAMLs can also be compared here: https://www.textcompare.org/yaml

2023r13

Content collection changes in content API

Content collections on series and parent series could already be managed from external systems using the content API.

Since the previous version, product versions can be linked indirectly to content collections in WHATS'ON Base. This happens when the Content collection includes all product versions check box is selected on a series with the Content collection structure (RN-6030).

From this version, the content API was adapted to include the product version changes.

The includesAllProductVersions attribute has been added to the body of the POST and PUT /contentCollections calls. When it is set to true, the check box will be selected on the content collection specified in the call. When it is set to false, the check box will be cleared. When it is not included in the call, the attribute is automatically set to false.

It has also been added to the response of the GET /contentCollections call.

{
    "contentId": "9422279527",
    "contentType": "season",
    "title": "FFG 2023",
    "duration": "01:30:00",
    "includesAllProductVersions": false,
    ...
}

Additionally, it became possible in a previous version to delete content collection items, even if they were planned. Message 5967 allows users to first consult the planning or unlink the items from their transmissions and delete the items anyway (RN-5887).

Previously, the DELETE /contentCollectionItems call would return an error message when trying to delete a planned content collection item.

     "errorCode": "CONTENT-00077",
     "description": "Content collection item could not be removed"

From this version, the DELETE /contentCollectionItems call will always delete the content collection item, meaning the error message is no longer shown. If the item was planned, the call will act as if Proceed was chosen on message 5967.

2023r11

Content collections on parent series in content API

In a previous version, content collections on parent series were introduced (RN-5754).

In this version, a number of changes have been done to include those in the content API.

While content collections on series can have two different structures, have their own external reference and are managed using the /season and /contentCollection calls, the content collections on parent series do not have a configurable structure or own external reference. They can only be edited by adding or removing items using the /contentCollectionItems calls, not the /series calls.

Changes were done to the following calls:

POST and PUT /series

The contentCollectionIntentions attribute has been added, which should be formatted as an array and can be used to set the intentions of the parent series content collection (RN-5574). The possible values can be retrieved using the GET /contentCollectionIntentions call.

       "contentCollectionIntentions": [
             "VOD",
             "Collection"
         ],

GET /series/{contentID}

This call can be used to retrieve the details of parent series, including which content collection items are linked to its content collection.

For this reason, the contentCollectionItemsIds and contentCollectionIntentions attributes have been added to the response of the call. The first one displays the external references of the content items linked to the content collection.

...
    "contentCollectionItemsIds": [
        "123456789",
        "987654321"
    ],
    "contentCollectionIntentions": [
        "VOD",
        "Collection"
    ],
...

DELETE /series

When a parent series is deleted, any linked content collection items will be removed and linked seasons are unlinked.

POST, PUT, GET and DELETE /contentCollectionItems

It is now also possible to use these calls for content collection items on parent series. The contentCollectionId attribute will then refer to the external reference of the parent series, as the content collection does not have its own external reference.

Other than this, there are no changes in behaviour.

GET /contentCollectionItemDisplayTypes

Additionally, each content collection item has a display type, for which the values come from the PSIContentCollectionItemDisplayType drop-down list.

This GET call has been added to retrieve the values of that drop-down list.

[
    {
        "id": "program",
        "name": "Program"
    },
    {
        "id": "episode",
        "name": "Episode"
    }
]

The id corresponds to the API reference of the drop-down values while the name represents the description.

The YAML of the content API has been updated for these changes.

2023r10

Fix for content running order references in content API

Previously, the YAML of the content API still contained references to content running orders, even though they were replaced by content collections in version 2023r5. This was the case in the description of the GET /products/{contentId} and the GET /targetGroups calls.

This issue has been fixed. The description of the GET /products/{contentId} has been changed and the GET /targetGroups call has been removed as it only applied to CROs.

2023r9

Genres in content API

In a previous version, a multi-selection Genre field was added on product level next to the previously existing single-selection field (RN-5633).

To allow external systems to edit these fields, from this version, both fields have been added to the content API.

A GET /genres call has been added to retrieve all values from the BOGenre drop-down list with their API reference and description.

[
    {
        "id": "Comedy",
        "name": "Comedy"
    },
    {
        "id": "Musical",
        "name": "Musical"
    }
]

In the following GET calls,

  • GET /products/{contentId}
  • GET /programs/{contentId}
  • GET /series/{contentId}
  • GET /seasons/{contentId}
  • GET /episodes/{contentId}
  • GET /contentCollections/{contentId}

the values for both fields are returned in the body.

{
    "contentId": "9294452527",
    "contentType": "program",
    "title": "Barbie",
    "duration": "01:40:00",
    ...
    "genre": "Comedy",
    "genres": [
        "Comedy",
        "Satire",
        "Oscar nominee"
    ]
}

They can also be updated using the following PUT and POST calls:

  • POST /programs
  • PUT /programs/{contentId}
  • POST /programs/{contentId}/versions/{versionId}
  • POST /series
  • PUT /series/{contentId}
  • POST /seasons
  • PUT /seasons/{contentId}
  • POST /seasons/{contentId}/versions/{versionId}
  • POST /episodes
  • PUT /episodes/{contentId}
  • POST /episodes/{contentId}/versions/{versionId}
  • POST /contentCollections
  • PUT /contentCollections/{contentId}

However, since these fields interact, both cannot be included in the same call. If this is the case, the following error message is returned:

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2023-09-29T09:22:05Z",
    "concept": "Program",
    "id": "9294452527",
    "errors": [
        {
            "errorCode": "CONTENT-00087",
            "description": "genre and genres cannot be both present at the same time.",
            "data": []
        }
    ]
}

When you include the genre field in a PUT call and the genres field already had multiple values, they will be replaced by the value in the body.

For example, my program had Comedy, Action and Blockbuster. When I include "genre": "Comedy" in the PUT call, then only Comedy remains in the Genre and Genres fields.

The YAML of the content API has been updated for these changes.

Parameter for episode inheritance in content API

A great deal of information on a series is shared among its episodes. In WHATS'ON Base, it is possible to propagate changes from series to episodes using inheritance settings. The default inheritance settings can be set in the general options and changed on individual series.

Previously, when updating a series using a PUT or POST /seasons call, it would be as if the inheritance method was set to Only if values are equal. It was not possible to change this. (See version 2022r10)

From this version, a parameter propagateToEpisodes can be added to the URL of the POST /seasons and PUT /seasons/{contentId} calls.

The possible values are:

  • onlyIfValuesAreEqual:

    • This represents the previous behaviour and is the default value when the parameter is not provided in the URL.

    • Changes are only propagated when episodes have the same value as the series.
      For example, a series and most episodes had a duration of 00:40:00 while one episode had a duration of 00:43:00. When the POST call changes the duration of the series to 00:47:00, then the series and the episodes that had 00:40:00 as duration will be updated.

  • always:
    The changes are always propagated to all the episodes, even if it means overwriting different values.

  • never:
    The changes are done only for the series and never inherited by the episodes.

An example of the URL with the parameter: PUT /seasons/{contentID}?propagateToEpisodes=always

This inheritance logic only applies to WHATS'ON series (seasons in the API). It does not work for parent series or for content collections.

The YAML has been updated for this change.

2023r6

Fix for modifying content collections using PUT /seasons call of content API

In the previous version, the content API was adapted for the introduction of content collections.

The PUT /seasons call should only be used to update a series with a standard season structure. However, previously, when the external reference of a content collection was provided in the PUT call, the update would still be executed.

This issue has been fixed. When the URL of the PUT /seasons call includes a reference to a content collection, the following error is returned:

{
    "statusCode": "404",
    "message": "The specified resource does not exist.",
    "timestamp": "2023-06-08T11:15:09Z",
    "concept": "Season",
    "id": "9006380527",
    "errors": [
        {
            "errorCode": "404",
            "description": "The specified resource does not exist.",
            "data": []
        }
    ]
}

 

2023r5

Content collections in season calls of content API

Previously, the content API had calls to manage content running orders, CRO elements and CRO press sheets. (See version 2022r10)

Since content running orders are removed from this version and replaced with content collections (RN-5572), the content API has also been adapted. Note that this is a breaking change, so the version number of the API was increased to 2.0.0 and this new version of the YAML should be retrieved to use these calls.

The existing season calls have been adapted for the introduction of content collections. They are used for updating WHATS'ON series with the Content collection structure set to Standard season. (RN-5571)

POST /seasons

This call is now used to create or update standard seasons.

In the background, the contentCollectionStructure attribute has been added but it should not be included as it will default to standardSeason. If it is included with the value contentCollection, it is ignored.

The contentCollectionIntentions attribute was also added, which should be formatted as an array and can be used to set the intentions. (RN-5574) The possible values can be retrieved using the GET /contentCollectionIntentions call.

    "contentCollectionIntentions": [
         "VOD",
         "Collection"
  ]

It is possible to specify a template parameter in the URL of the call, corresponding to a series prototype. Since the content collection structure can also be set on a prototype (RN-5571), it is checked whether the provided template has a Standard season or empty structure. If it has Content collection, a 422 error message is returned with the following description:

    "errorCode": "CONTENT-00074",
     "description": "$_The content collection structure of the template does not correspond with the content collection structure of the BAPI call executed.",
     "data": []

PUT /season/{contentID}

This call can be used to update a standard season. If a content collection series is updated, an error is returned.

The contentCollectionIntentions attribute was also added to this call and behaves the same as in the POST call.

The structure on a series cannot be updated with this call. Therefore, the contentCollectionStructure attribute should not be included as it will default to standardSeason.

GET /season/{contentID}

This call retrieves all details of a standard season.

The contentCollectionIntentions and contentCollectionStructure attributes have been added to the response of the call.

...
    "contentCollectionIntentions": [
        "VOD",
        "Collection"
    ],
    "contentCollectionStructure": "standardSeason",
...

If the contentId provided in the URL corresponds to a series with Content collection structure, a 404 error is returned since this call is only intended for standard seasons.

     "errorCode": "404",
      "description": "The specified resource does not exist."

POST /seasons/{contentId}/versions/{versionId}

This call is used to create a new version for standard seasons.

The contentCollectionIntentions attribute was also added to this call and behaves the same as in the POST and PUT /seasons call.

If the contentId provided in the URL corresponds to a series with Content collection structure, a 422 error is returned since this call is only intended for standard seasons.

     "errorCode": "CONTENT-00075",
      "description": "$_A series with a content collection structure cannot have multiple product versions.",

It is not possible to create another version of a content collection. (RN-5598)

The content collection items of a standard season correspond to regular episodes so they should be updated using the /episodes calls.

For series with Content collection as structure, the content collection calls should be used.

Content collection calls in content API

Previously, the content API had calls to manage content running orders, CRO elements and CRO press sheets.

Since content running orders are removed from this version and replaced with content collections, the content API has also been adapted. Note that this is a breaking change, so the version number of the API was increased to 2.0.0 and this new version of the YAML should be retrieved to use these calls.

The content running order and content structure calls have been removed and replaced by the following content collection calls. These should be used for WHATS'ON series with the Content collection structure set to Content collection. (RN-5571)

POST /contentCollections?template=[API reference]

This call can be used to create or update content collection series.

The body is similar to that of the POST /season call except that it contains contentCollectionItemIds instead of episodeIds. The title and duration attributes are mandatory. Since content collections can also be added to parent series, the seriesId attribute is also present in the call.

The contentCollectionIntentions attribute is also part of this new call and behaves the same as in the season calls.

The contentCollectionStructure attribute should not be included as it will default to contentCollection. If it is included with the value standardSeason, it is ignored.

A full description of the call body can be found in the API explorer or the YAML.

It is possible to specify a template parameter in the URL of the call, corresponding to a series prototype. Since the content collection structure can also be set on a prototype (RN-5571), it is checked whether the template has a Content collection or empty structure. If it has Standard season, a 422 error message is returned with the following description:

     "errorCode": "CONTENT-00074",
      "description": "$_The content collection structure of the template does not correspond with the content collection structure of the BAPI call executed.",
      "data": []

PUT /contentCollections/{contentID}

This call can be used to update a content collection. If a standard season series is updated, a 404 error is returned:

    "errorCode": "404",
     "description": "The specified resource does not exist.",

The contentCollectionIntentions attribute is also available in this call and behaves the same as in the POST call.

A full description of the call body can be found in the API explorer or the YAML.

The structure of a series cannot be updated with this call. Therefore, the contentCollectionStructure attribute should not be included as it will default to contentCollection.

GET /contentCollections/{contentID}

This call returns all the details of a content collection. If the provided contentId responds to a standard season series, a 404 error is returned.

The response body resembles that of the GET /season call. A full description can be found in the API explorer or the YAML.

DELETE /contentCollections/{contentId}

This call will delete the content collection with the provided contentId, if it was not yet linked to a transmission. If so, a 422 error is returned:

     "errorCode": "CONTENT-00076",
      "description": "Content collection could not be removed",

If the contentId corresponds to a standard season, a 404 error is returned since only content collections can be deleted using this call.

GET /contentCollectionIntentions

This call can be used to retrieve the values of the PSIContentCollectionIntention drop-down list.

[
    {
        "id": "VOD",
        "name": "VOD"
    },
    {
        "id": "Best of",
        "name": "Best of"
    }
]

The id corresponds to the API reference of the drop-down values while the name represents the description.

Content collection item calls in content API

Previously, the content API had calls to manage content running orders, CRO elements and CRO press sheets.

Since content running orders are removed from this version and replaced with content collections, the content API has also been adapted. Note that this is a breaking change, so the version number of the API was increased to 2.0.0 and this new version of the YAML should be retrieved to use these calls.

The items of a content collection (RN-5577) cannot be updated by the existing /episodes calls, but should be updated using the following dedicated calls.

POST /contentCollectionItems

This call can be used to add content to a content collection, thus creating content collection items.

The body consists of the following attributes:

{
    "contentId": "3261665527",
    "contentCollectionId": "9196369527"
    "id": "HP1",
    "displayNumber": 1,
    "displayType": "programType",
}

The contentId and contentCollectionId are mandatory for creating an item. If they are not included, a 422 error is returned:

     "errorCode": "CORE-00010",
      "description": "The field 'contentId' is mandatory when creating this concept.",
      "data": [
         "contentId"
            ]

If they are added to the call for an update, the values cannot be different as you cannot change the content of an item or the content collection it is part of. If they are different, a 422 error is returned.

    "errorCode": "CONTENT-00082",
     "description": "It is not possible to update the content collection to which this item belongs",

The contentId refers to the external reference of the content you want to add to the collection. This can be programs, episodes or interstitials. When the reference of a series or parent series is provided, a 422 error is returned:

   "errorCode": "CONTENT-00084",
    "description": "Standard seasons, content collections or parent series cannot be added as items to a content collection",

The id is the external reference of the content collection item.

The contentCollectionId corresponds to the external reference of the content collection you want to add the item to. If the reference of a standard season is provided, a 422 error is returned because only content collections can be used.

It is possible to limit content to be part of only one content collection with a certain intention. (RN-5574) When you use the POST call to add it to another one, the following error will be returned:

     "errorCode": "5886",
      "description": ""[program]" is already part of a content collection with intention "VOD" and cannot be added once more."

PUT /contentCollectionItems/{contentCollectionItemId}

This call can be used to update the external reference, display number and display type of a content collection item.

Note that it is not possible to change the content or the content collection it is part of. For this, the item should be deleted and recreated.

The body contains the following attributes:

{
  "id": "1705202310",
  "displayNumber": "1",
  "displayType": "clip"
}

If the id is provided and is different from the contentCollectionItemId in the URL, the external reference is updated with the value from the id attribute.

GET /contentCollectionItems/{contentCollectionItemId}

This call retrieves all the details of the content collection item with the provided external reference. The response contains the following attributes:

{
    "id": "HP1",
    "orderNumber": 1,
    "displayNumber": null,
    "displayType": "programType",
    "contentId": "3261665527",
    "contentType": "program",
    "version": "Default",
    "contentCollectionId": "9196369527"
}

They correspond to the properties seen in the content collection items list. (RN-5577)

DELETE /contentCollectionItems/{contentCollectionItemId}

This call can be used to delete a content collection item.

If the item had already been linked to a transmission, it cannot be deleted so a 422 error is returned:

     "errorCode": "CONTENT-00077",
      "description": "Content collection item could not be removed",

2023r4

Manage product titles in content API

In WHATS'ON, products can have different titles, such as original titles, translated titles, alternative titles, etc.

Previously, it was already possible to update the titles of content using the content API. However, if a single title needed to be updated, the entire list of titles needed to be provided.

To make it easier to update individual titles, the following calls are available:

GET /titles/{title_id}

The external reference of the title should be provided in the URL. The response then returns the details of that specific title:

{
    "id": "6176112544",
    "contentId": "143048527",
    "title": "MCU23",
    "type": "SubTitle",
    "alternativeTitle": false,
    "broadcastingTitle": false
}

POST /titles

This can be used to create a new title. The contentId and type are mandatory attributes.

PUT /titles/{title_id}

This can be used to update an existing title.

If a call would update the titles of a product so no titles would remain as broadcasting title, an error code is returned.

DELETE /titles/{title_id}

This can be used to delete one specific title. If the title is marked as the broadcast or alternative title, it cannot be deleted and an error message is returned.

Additionally, the id attribute has been added to each title in the productTitles array in the following calls:

  • GET /products

  • GET /programs/{contentId}

  • GET /series/{contentId}

  • GET /seasons/{contentId}

  • GET /episodes/{contentId}

An example of the GET /programs call:

    "productTitles": [
        {
            "id": "143049544",
            "type": "OriginalTitle",
            "title": "AVENGERS: ENDGAME",
            "alternativeTitle": true,
            "broadcastingTitle": true
        },
        {
            "id": "6176112544",
            "type": "SubTitle",
            "title": "MCU23",
            "alternativeTitle": false,
            "broadcastingTitle": false
        }
    ]

2023r3

Inheritance of images in content API

In the previous version, changes were made in the content API because of the move of images from press sheets to content.

Additionally, in WHATS'ON, the inheritance of images was enabled again from series to episodes. (RN-5435)

However, this inheritance did not yet happen when using the content API.

This issue has been fixed. Now, when sending a PUT or POST /seasons call to update images on a series, the images are inherited by the episodes or other versions following the Only if values are equal inheritance setting in the general options.

This means they are inherited by the episodes, but only if the episode was already created for the series. If the episode is added later, the images are not propagated until the images are changed on the series.

Images in GET /pressSheets call of content API

Previously, images were moved from press sheets to content level. In the previous version, the content API was adapted for this change. This included removing the images array from the GET /pressSheets call.

However, to ensure compatibility, a Press target field was added to images. Therefore, it should be possible to retrieve the images formerly linked to press sheets of certain targets. For this reason, the images array has been added to the GET /pressSheets call again.

It returns all the images of the product for which the value of the Press target field is the same as that of the press sheet retrieved by the GET call.

For example, a film has two press sheets: one with target English and one with target French. It has 3 images:

  • Image 1 with press target English

  • Image 2 with press target French

  • Image 3 with press target English and French

If I send a GET /pressSheets call with the ID of a press sheet with target English, the images attribute would be an array with the details of image 1 and 3. 

{
    "pressSheetId": "9065887828",
    "pressTarget": "Default",
    "pressStatus": null,
    "contentId": "7092611527",
    "title": "FOR ALL MANKIND",
     ...
    "seriesTitle": null,
    "images": [
        {
            "imageId": "6231653000",
            "highResolutionURL": "//poster-e1616427715306.jpg",
            "identification": "W9287"
        }
    ]
}

2023r2

Images on content in content API

In a previous version, images were moved from press sheets to content level. (RN-5333)

From this version, the content API has also been adapted for this change. A new version of the YAML should be retrieved to use these attributes and calls. This can be done via the GET /api call.

GET /products, /programs, /episodes, /seasons, /series

An images attribute has been added to the response body of the calls:

"images": [
        {
            "imageId": "6318876000",
            "highResolutionURL": https://wikipedia/image.jpg\,
            "identification": "EN",
            "pressTargets": [
                "English",
                "Print"
            ]
        }
]

It returns an array of all images on the product matching the content ID defined in the call. Each image has the following attributes:

  • imageId:
    The external reference of the image. Note that this corresponds to the Image\External reference column in the IMAGES list while the External reference column (without the prefix) refers to the link between the product and the image, not the actual image.

  • highResolutionURL: The URL defined in the High resolution URL field.

  • identification: The Identification of the image.

  • pressTargets: An array with the API references of all the Press target values (RN-5334) on the image.

POST and PUT /programs, /episodes, /seasons, /series and /versions

The images array above can also be added to the body of the POST and PUT calls, but it is not mandatory. None of the attributes inside the array are mandatory either.

When the call is used to update a product or product version, all images on the product are replaced by the ones provided in the array.

When the specified imageId cannot be found, a new image will be created and linked to the product.

If the API references in the pressTargets array are not found in the WOnPressTarget drop-down list, or a value appears twice in the array, an error code is returned.

POST and PUT /pressSheets

To ensure compatibility with older versions, the existing images attribute can still be used. However, images will still be created on the product instead of the press sheet.

{
  "pressSheetId": "8946250095",
  "contentId": "143048527",
  "pressTarget": "English",
  "pressStatus": "Ready",
  "title": "AVENGERS: ENDGAME",
  "images": [
    {
      "imageId": "8946074000",
      "highResolutionURL": null,
      "identification": null
    }
  ]
}

Since the contentId attribute is mandatory in the POST call, it is now used to identify the product and create or link the images to that product instead of the press sheet. The value of the mandatory pressTarget attribute is added to the Press targets field (RN-5334) on the image. Note that only one value can be provided here, even though it is a multiselection drop-down list on the image.

For the PUT call, only the pressSheetId is mandatory, which is used to identify the product. Since the pressTarget is optional, a value will not be added to the image if the attribute is not provided.

The images on the product are always replaced with the images provided in the images array of the press sheet calls.

When you add the pressTarget attribute manually to the images array, (as is possible in the product calls) its value will be ignored in these calls because the press target of the image is taken from the attribute in the main call.

GET /pressSheets

Since press sheets no longer have images, the images attribute has been removed from the response of the GET call.

Additional attributes in content API

Aside from the changes in the content API to move images to content level, additional attributes have also been added to several calls. A new version of the YAML should be retrieved to use these attributes and calls. This can be done via the GET /api call.

GET, POST and PUT /products, /programs, /episodes, /seasons, /series and /versions

They have a similar label in the system default layout of the product navigator unless otherwise specified.

  • productionNumber

  • origin

  • contentProducer: called Produced by in the system default layout of the product navigator

  • contentCode

  • keywords

  • frequency

  • videoFormat

  • productionMode

  • sound

  • appreciation

  • planningCategories

  • countryOfSubject: called Region of subject in the system default layout of the product navigator

  • contractRequired

When updating these fields on a season using the PUT or POST /seasons call, they will also be inherited to the episodes if the initial values were equal. (See version 2022r10)

Some of these attributes are drop-down lists. Therefore, the following GET calls have been added to retrieve the values of these drop-down lists:

  • GET /origins for drop-down list PSIOrigin

  • GET /contentProducers for WOnContentProducer

  • GET /contentCodes  for WOnContentCode

  • GET /frequencies for PSIFrequency

  • GET /videoFormats for PSIVMVideoFormat

  • GET /productionModes for PSIProductionMode

  • GET /planningCategories for PLPlanningCategory

  • GET /appreciations for Quotation

  • GET /sound for Sound

GET, POST and PUT /pressSheets

The following attributes have been added:

  • shortTeletext: called Short teletext description on a press sheet

  • seriesTitle: a field called Parent series title that should be added to a press sheet through layout configuration

Fix for external reference of interstitial in GET /products call of content API

A GET /products call exists in the content API to retrieve the details of a product regardless of the type.

Previously, when the external reference of an interstitial was provided in the URL of the call, the BAPI service would crash as the call is not intended to find interstitials.

This issue has been fixed. When the external reference of an interstitial is provided, a 404 error code is returned, saying that the specified resource does not exist, as no product with that reference could be found.

Fix for episode inheritance of custom attributes in content API

Custom attributes can be used in several calls in the content API.

Previously, a fix was done to enable inheritance from series to episodes when changes were done through PUT or POST /seasons call in the content API.

However, this did not apply to custom attributes yet.

This issue has been fixed. Now, when sending a PUT or POST /seasons call to update custom attributes, the values will be inherited by the episodes but only if their initial value was the same.

For example, a series and its episodes have value A for a custom attribute of type Drop-down list. I change the custom attribute to value B on episode 1 only. When I send a POST call that changes the custom attribute of the series to value C, then the series and all episodes except episode 1 will be updated because those had the same values, while episode 1 had a different value.

2022r10

Extra custom attribute types in content, MAM and trailer API

Previously, the content, MAM and trailer API already supported the following custom attribute types:

  • Boolean

  • Date

  • Drop-down

  • Integer

  • Reference

  • String

  • Text

  • Web

From this version, the following types have been added:

  • Duration:
    With default format HH:MM:SS:iii

  • Decimal number:
    A period should be used as decimal and maximum two digits after the decimal will be returned.

  • Drop-down list for multiselection

They have been added to the calls that already supported custom attributes. A new version of the YAMLs can be retrieved to use these attributes.

In the GET calls, the following suffixes can be added to the call to either get only specified attributes in the response or all custom attributes of the supported types:

  • ?customAttributes=attributeName,attributeName

  • ?customAttributes=allCustomAttributes

For each custom attribute, the attribute name, value and type will be given. The new types will be included in the response as follows:

    "customAttributes": [
        {
            "attributeName": "customMultiMA",
            "value": [
                "Value1",
                "Value2"
            ],
            "type": "Drop-down list for multiselection"
        },
        {
            "attributeName": "cADecimal",
            "value": 2.64,
            "type": "Decimal number field"
        },
        {
            "attributeName": "cADuration",
            "value": "02:03:04.000",
            "type": "Duration field"
        }
    ]

In POST or PUT calls, an array of custom attributes needs to be provided with their attribute name and value. If the value is left empty by using null or "" for some types, the custom attribute is emptied. The new types should be specified as follows:

    "customAttributes": {
        "cADecimal": 1.23,
        "cADuration": "01:32:20.000",
        "customMultiMA": ["TestWOnDynamicDomain23"]
    }

GET /products call in content API

Previously, in the content API, a GET call needed to be used per type of content:

  • GET /programs

  • GET /episodes

  • GET /seasons

  • GET /series

From this version, a new call, GET /products/{contentId}, was added. It allows you to search for content regardless of the type. It will use the provided content ID to identify the content type and return the relevant attributes. These attributes are the same as in the existing GET calls.

It is also possible to add the custom attributes parameter or debug parameters (RN-4469) to the call URL.

Content running orders in content API

In a previous version, content running orders were introduced for more flexible planning. (RN-3641) However, they were not yet part of the content API.

From this version, the following was added or changed to include them in the content API:

New calls

GET, POST and PUT /contentRunningOrders

Content running orders can only be created, edited and retrieved in full with the these specific calls, not using the product calls. It is also possible to create content structures using the type. (RN-4496)

GET, POST, PUT and DELETE /contentRunningOrderElements

Products can only be added to or removed from content running orders using these calls, not using the product calls.

POST /contentRunningOrderElementsForSeries

This call can be used to add all episodes of a series at once to a content running order.

GET, POST, PUT and DELETE /pressSheetsCRO

Press sheets on content running orders can only be created or edited with these specific calls, not the content press sheet calls.

More information on how to configure them can be found in the YAML.

Existing calls

GET /programs and /episodes

The following attributes were added:

"displayType": "program"
 "defaultStructureSeries": "12345678"
 "defaultContentStructure": "12345678"
 "contentRunningOrderElements": [
        {
            "contentRunningOrderElementId": "7445097000",
            "contentRunningOrderId": "7445093000",
            "contentId": "143048527",
            "orderNo": 2,
            "displayType": "programType",
            "displayNumber": null,
            "displaySeason": null,
            "version": "Default",
            "isDefault": false,
            "seasonId": "7445043527",
            "displayTypeCRO": null,
            "displaySeasonCRO": null
        }
    ]

This represents a list of content running order elements linked to the product and its properties in the content running order.

PUT, POST /programs, /episodes, /seasons and versions

The following attributes were added:

"displayType": "string"
 "defaultContentStructure": "string"

GET /season 

"displayType": "series",
 "defaultStructureSeries": null,
 "defaultContentStructure": null, 
 "contentRunningOrders": [
        {
            "contentRunningOrderId": "7445093000",
            "type": null,
            "isStructure": false
        }
    ]

This represents a list of content running orders created on the series.

Additional drop-down list calls

  • /productDisplayTypes:
    For the PSIProductDisplayType drop-down list

  • /contentRunningOrderDisplayTypes:
    For the PSIContentRunningOrderDisplayType drop-down list

  • /contentRunningOrderTypes:
    For the PSIContentRunningOrderType drop-down list

  • /contentRunningOrderElementTypes:
    For the PSIContentRunningOrderElementType drop-down list

  • /psiContents:
    For the PSIContents drop-down list

  • /targetGroups:
    For the TargetGroup drop-down list

  • /croExternalDisplayInstructions:
    For the CROExternalDisplayInstruction drop-down list

Fix for inheritance from series to episodes in content API

Previously, when updating a series using a PUT or POST /seasons call, then no changes were propagated to its episodes.

This issue has been fixed. The episodes that had the same values for the updated properties will inherit the changes, as if the inheritance method was set to Only if values are equal.

For example, a series and most episodes had a duration of 00:40:00 while one episode had a duration of 00:43:00. When the POST call changes the duration of the series to 00:47:00, then the series and the episodes that had 00:40:00 as duration will be updated.

2022r8

Contact person added to GET, POST and PUT calls of content API

The contactPerson attribute has been added to the

  • response of the GET

    • /program

    • /seasons

    • /series

    • /episodes calls,

  • body of the PUT and POST

    • /program

    • /seasons

    • /series

    • /episodes calls

of the content API.

A new version of the YAML should be retrieved to use this attribute.

The attribute corresponds to the external reference of the person linked as contact person. When no persons with the defined reference can be found or when multiple persons exist with the reference, the appropriate error messages are returned.

{
    "statusCode": "422",
    "message": "Operation cannot be completed due to violations",
    "timestamp": "2022-11-30T15:29:33Z",
    "concept": "Program",
    "id": "1401698527",
    "errors": [
        {
            "errorCode": "CONTENT-00035",
            "description": "No person found with id BAPI",
            "data": [
                "BAPI"
            ]
        }
    ]
}

2022r7

Fix for clearing parental ratings in PUT and POST calls of content and MAM API

Parental ratings on content and media assets are defined per regulator. This means they are represented as an array in API calls:

    "ratings": [
        {
            "regulator": "localRegulator",
            "rating": "12",
            "reason": null
        },
        {
            "regulator": "Ofcom",
            "rating": "allAges",
            "reason": null
        }
    ]

Previously, when trying to clear the ratings while updating a product or media asset by leaving the "rating": null in the PUT or POST calls of the APIs, an error message would appear saying the rating was invalid.

This issue has been fixed. When specifying null as value for the rating attributes, then the specific rating will be cleared. When sending null for the ratings array, all ratings per regulator will be deleted.

2021r2.000

API version: v1.3.1

More custom attribute types

See release notes of version 2021r2.001.

Since version 2020r2.002, a number of types of custom attributes were already supported by the content API:

  • Check boxes
  • Drop-down lists
  • String fields

They could be included in the body of the PUT and POST calls and included as parameters in the GET call.

From this version, support for the following types has been added:

  • Date fields
  • Number fields
  • Reference fields
  • Text fields
  • Web fields

In the GET calls, the following suffixes can be added to the call to either get only specified attributes in the response or all custom attributes of the supported types:

  • ?customAttributes=attributeName,attributeName
  • ?customAttributes=allCustomAttributes

For each custom attribute on the product, the attribute name, value and type will be given. For the reference custom attributes, the referenced concept is also included:

{    "customAttributes": [
        {
            "attributeName": "cADate",
            "value": "2021-10-04",
            "type": "Date field"
        },
        {
            "attributeName": "cAMediaAsset",
            "value": "6111521000",
            "type": "Reference field",
            "concept": "Media asset"
        },
        {
            "attributeName": "cANumber",
            "value": 1,
            "type": "Number field"
        },
        {
            "attributeName": "cAText",
            "value": "Shaken, not stirred",
            "type": "Text field"
        },
        {
            "attributeName": "cAWeb",
            "value": "https://www.geekster.be/",
            "type": "Web field"
        }
    ]
}

In the POST and PUT calls, an array of custom attributes needs to be provided with their attribute name and value. If the value is left empty by using null or "" for some types, the custom attribute on the product is emptied.

{
    "contentId": "PGM001",
    "customAttributes": {
        "cADate": "2021-10-01",
        "cAMediaAsset": "3350456000",
        "cANumber": "10",
        "cAText": "I am inevitable",
        "cAWeb": "https://www.geekster.be"
    }
}

Debug parameters

See release notes of version 2021r2.001.

Using the GET calls in the content API, you can retrieve the metadata properties of products in WHATS'ON. However, it was not possible to retrieve more technical information such as the date the product was created or last modified.

From now on, a debug parameter can be added to the GET calls (but not search calls) for all product types in the content API.

It is possible to mention the specific parameters and separate them using commas or to include all:

  • :contentId?debug=dateCreatedUTC,dateModifiedUTC
  • :contentId?debug=all

An example:

basepath/content/v1/programs/6629341527?debug=dateCreatedUTC

The response of the GET call will then include these parameters in a separate attribute converted to UTC time.

The format will be [YYYY-MM-DD]T[HH:MM:SS.MSMSMS][+HH:00] where the final part represents the time difference to UTC time.

For example:

{
    "contentId": "6629341527",
    "contentType": "program",
    "title": "SHANG-CHI AND THE LEGEND OF THE TEN RINGS",
    "duration": "02:00:00",
    "debugInfo": {
        "dateCreatedUTC": "2021-10-01T11:45:27.900+02:00",
        "dateModifiedUTC": "2021-10-01T11:45:42.032+02:00"
    }
}

When the debug parameter is not in the call, it is not visible in the response. When it is in the call but it is not included correctly, the following response will be returned:


{
    "statusCode": "400",
    "message": "Bad Request",
    "timestamp": "2021-10-01T12:13:10Z",
    "concept": "Program",
    "id": "6629341527",
    "errors": [
        {
            "errorCode": "CORE-00007",
            "description": "Invalid debug attributes",
            "data": [
                "dateCreatedUT"
            ]
        }
    ]
}

2021r2.000

API version: v1.1.0

Custom attributes

From this version on, it is possible to include custom attributes in the calls of the content API.

  • Check boxes
  • Drop-down lists
  • String fields

They could be included in the body of the PUT and POST calls and included as parameters in the GET call.

2021r1.000

Press sheets in content API

From this version, it is possible to create, update and delete press sheets via the content API.

New calls are added:

  • POST pressSheets
  • PUT pressSheets/{pressSheetId)
  • GET pressSheets/{pressSheetId)
  • DELETE pressSheets/{pressSheetId)
  • GET pressTargets
  • GET pressStatus
  • GET parentalRatings

Some existing calls got an extra section in their response detailing the existing press sheets:

  • GET programs/{contentId}
  • GET series/{contentId}
  • GET season/{contentId}
  • GET episodes/{contentId}

2020r2.002

Improvements to content API

As from this version, the Description field of the Descriptions tab of the product navigator is also added to the content API. It is available for all POST, PUT and GET calls for content (programs, episodes, series, seasons). Also the Distributor number for episodes is added to POST, PUT and GET calls. Extra drop down fields have been added to the content schema as well:

  • originalLanguage

  • contentTargetGroup

  • content

  • form

  • broadcastMedium

This makes them available for product, series, season & episode calls. Furthermore, support for TitleTypes, for custom attributes on the concept Program and for the cast list has been added to the content API.

2020r1.002

API version: v1.0.1

External reference cannot be cleared by BAPI

Within any POST and PUT call, if a an attribute is sent empty, WHATS'ON will clear that field. Previously, this was also possible with the external reference of content.

Now, this is fixed. When no external reference is provided but the attribute is sent empty or Null, we will ignore that tag and proceed as if there was no ID field (external reference) provided. This means that it should remain as is in a PUT call or return a new one in a POST call.

2017r1.005

API version: v1.0.0

Addition of Content API

From this version on, it is possible to manage content using the Content API.